package com.chatmcp.mcprouter.service;

import com.chatmcp.mcprouter.dto.ServerConfigDto;
import com.chatmcp.mcprouter.jsonrpc.JsonRpcRequest;
import com.chatmcp.mcprouter.jsonrpc.JsonRpcResponse;
import com.chatmcp.mcprouter.jsonrpc.Tool;

import java.util.List;
import java.util.function.Consumer;

/**
 * MCP客户端服务接口
 * 负责与MCP服务器进行通信
 */
public interface McpClientService {

    /**
     * 创建新的客户端连接
     *
     * @param serverConfig 服务器配置
     * @return 是否成功
     * @throws Exception 如果连接失败
     */
    boolean connect(ServerConfigDto serverConfig) throws Exception;

    /**
     * 关闭客户端连接
     */
    void close();

    /**
     * 断开客户端连接
     * 与close()不同，这个方法仅断开连接而不释放资源
     */
    void disconnect();

    /**
     * 检查客户端是否已连接
     *
     * @return 是否已连接
     */
    boolean isConnected();

    /**
     * 检查客户端是否出错
     *
     * @return 错误信息，如果没有错误则返回null
     */
    String getError();

    /**
     * 设置通知回调
     *
     * @param callback 回调函数
     */
    void setNotificationCallback(Consumer<String> callback);

    /**
     * 发送请求到MCP服务器并等待响应
     *
     * @param request JSON-RPC请求
     * @return JSON-RPC响应
     * @throws Exception 如果发送失败
     */
    JsonRpcResponse sendRequest(JsonRpcRequest request) throws Exception;

    /**
     * 转发消息到MCP服务器
     *
     * @param request 请求消息
     * @return 响应消息
     * @throws Exception 如果转发失败
     * @deprecated 请使用 {@link #sendRequest(JsonRpcRequest)}
     */
    @Deprecated
    JsonRpcResponse forwardMessage(JsonRpcRequest request) throws Exception;

    /**
     * 初始化完成后发送通知
     * 
     * @return 是否成功
     * @throws Exception 如果发送失败
     */
    boolean notificationsInitialized() throws Exception;

    /**
     * 获取工具列表
     *
     * @return 工具列表
     * @throws Exception 如果获取失败
     */
    List<Tool> listTools() throws Exception;

    /**
     * 调用工具
     *
     * @param name      工具名称
     * @param arguments 工具参数
     * @return 工具调用结果
     * @throws Exception 如果调用失败
     */
    Tool.CallToolResult callTool(String name, Object arguments) throws Exception;
} 